home *** CD-ROM | disk | FTP | other *** search
/ NOVA - For the NeXT Workstation / NOVA - For the NeXT Workstation.iso / SourceCode / Executive / Executive.h < prev    next >
Text File  |  1992-12-19  |  5KB  |  134 lines
  1. /*------------------------------------------------------------------------------
  2.     Executive.h                Copyright (c) 1990, Marc A. Davidson
  3.  
  4.     REVISIONS
  5.     Date            Who        Modification
  6.     24-Sept-90    MAD        Created (simple synchronous routines)
  7.     5-Oct-90        MAD        Added cthread routines and queues for executing 
  8.                                 asynchronous commands.
  9. ------------------------------------------------------------------------------*/
  10. # import <objc/Object.h>
  11. # import <cthreads.h>
  12.  
  13. # define CSTR    const char *
  14.  
  15. @interface Executive:Object
  16.  /*
  17.   * Executive allows the execution of shell commands from a program, providing
  18.   * both synchronous and asynchronous execution of commands.  Other features
  19.   * include the ability to direct command output to another object through the
  20.   * popen(3) mechanism and displaying of errors through a standard panel for
  21.   * consistency in error reporting throughout an application.
  22.   */
  23. {    id                    target;
  24.     SEL                action;
  25.     double            period;                    /* period at which entry gets called */
  26.     /*
  27.      * internal instance variables
  28.      * @public is set for these since the internal commands need to acces
  29.      * them via self->xxx.
  30.      */
  31. @public
  32.     int                curCmdId;                /* current command id in use */
  33.     int                numExecuting;            /* number of commands currently executing */
  34.     mutex_t            runningLock;            /* for access to running queue */
  35.     mutex_t            doneLock;                /* for access to done queue */
  36.     id                    running;                    /* queue for commands that are executing */
  37.     id                    done;                        /* queue for commands that are done */
  38. }
  39.  
  40. + new;
  41.  /*
  42.   * Allocates a new Executive object with the default period for updating during
  43.   * asynchronous commands.
  44.   */
  45.  
  46. + newPeriod:(double)p;
  47.  /*
  48.   * Allocates a new Executive object with the specified period for updating
  49.   * during asynchronous commands.
  50.   */
  51.  
  52. - target;
  53. - setTarget:anObject;
  54. - (SEL) action;
  55. - setAction:(SEL)aSelector;
  56.  /*
  57.   * Sets the target and action of the Executive for commands that are executed
  58.   * asynchronously.
  59.   */
  60.  
  61. - setPeriod:(double)p;
  62. - (double)period;
  63.  /*
  64.   * Sets and queries the period instance variable.
  65.   */
  66.  
  67. - (int) execute:(CSTR)command;
  68. - (int) execute:(CSTR)command async:(BOOL)async;
  69. - (int) execute:(CSTR)command environs:(CSTR)environs async:(BOOL)async;
  70.  /*
  71.   * The execute suite of methods execute a given command either synchronously or
  72.   * asynchonously.  If the command is executed synchronously the result of the
  73.   * system() call is returned by the method.  Otherwise, the result returned is
  74.   * a unique identifier for this command (a small positive integer value). The
  75.   * target is notified when the command completes.  The action that the target
  76.   * implements should be a method that takes two arguments: the command number
  77.   * (as returned by execute:async: or execute:async:environs:) and the result of
  78.   * the system() call (i.e. commandComplete:(int)cmdNum withResult:(int)result).
  79.   *
  80.   *    SEE ALSO:
  81.   *        system(3) for result codes returned.
  82.   */
  83.  
  84. - (int)pipe:(CSTR)command to:anObject :(SEL)aSelector async:(BOOL)async;
  85. - (int)pipe:(CSTR)command environs:(CSTR)environs to:anObject :(SEL)aSelector
  86.     async:(BOOL)async;
  87.  /*
  88.   * The pipe methods execute a popen() call that will send the results of
  89.   * reading a pipe to the specified object with a selector that takes either
  90.   * one or two arguments.  If the pipe is executed asynchronously, the selector
  91.   * should be for a method that takes two arguments, that of the command number
  92.   * and one line that was read from the pipe
  93.   * (i.e. processFrom:(int)cmdId line:(const char *)line).
  94.   * When the asynchronous command completes it notifies the target of the object
  95.   * (see above under execute: for notifying behavior).
  96.   * If the pipe is executed synchronously, the selector method should accept one
  97.   * argument, that of the line read (i.e. processLine:), complete with newline.
  98.   * The result returned is either 0 or a unique identifier for the asynchronous
  99.   * command (a small positive integer value, same as execute: above).
  100.   */
  101.  
  102. - showError:(int)err;
  103. - showError:(int)err while:(CSTR)doingWhat;
  104. - showError:(int)err while:(CSTR)doingWhat on:(CSTR)fname;
  105. - showError:(int)err while:(CSTR)doingWhat on:(CSTR)fname using:(CSTR)prog;
  106.  /*
  107.   * showError allows the application to have a regular set of error-reporting
  108.   * abilities in various degrees of granularity.
  109.   * The area in the upper portion of the NXRunAlertPanel panel will be the text
  110.   * (by named parameter) "<prog> error"
  111.   * The lower part will have the text "Error while <doingWhat> <fname>
  112.   * (error code <err>)"
  113.   *
  114.   * All of the methods eventually call showError:while:on:using:.  If any of the
  115.   * more general methods are called, they substitute defaults for the missing
  116.   * parameters.
  117.   *
  118.   * The defaults for these methods are:
  119.   *
  120.   *        doingWhat    defaults to "executing a command"
  121.   *        fname            defaults to "on a file"
  122.   *        prog            defaults to "File"
  123.   */
  124.  
  125. - showFError:(CSTR)fname;
  126.  /*
  127.   * showFError is used when a file error occurs during a system call.  It takes the
  128.   * file name given and presents it with the text of the error recorded in the
  129.   * errno global variable.
  130.   */
  131.  
  132. @end
  133.  
  134.